Inside Macintosh: QuickDraw GX Graphics /

Chapter 2 - Geometric Shapes / Geometric Shapes Reference

Functions / Editing Shape Geometries

GXGetShapePoints

You can use the GXGetShapePoints function to obtain a copy of a range of geometric points from a specified shape.

long GXGetShapePoints(gxShape source, long index, long count, 
                      gxPoint data[]);

source

A reference to the shape containing the desired geometric points.

index

The geometry index of the first geometric point to copy.

count

The number of the geometric points to copy. You may provide the gxSelectToEnd constant for this parameter.

data

A pointer to an array of gxPoint structures. On return, this array contains the copied points.

function result

The number of geometric points copied.

DESCRIPTION

The GXGetShapePoints function returns in the data parameter a copy of the geometric points from the source shape's geometry starting from the geometric point with the geometry index indicated in the index parameter.

You provide, in the count parameter, the number of geometric points you want copied. The function result is the actual number of points copied. Typically, the value you provide for the count parameter is the same as the function result returned by this function. There are two exceptions:

• If you provide too large a value for the count parameter--that is, the geometry of the source shape does not have enough geometric points to satisfy your request--this function copies as many geometric points as the shape does have (starting from the geometric point with the geometry index indicated by the index parameter). In this case, the function posts a count_out_of_range warning, and the function result reflects the actual number of geometric points copied.
• Similarly, if you set the count parameter to the gxSelectToEnd constant, the function copies as many geometric points as the shape has, starting from the geometric point with the geometry index indicated by the index parameter. In this case, the function result reflects the actual number of geometric points copied, but no warning is posted.

Notice that this function returns the copied points as a single point array. If the source shape is a polygon or path shape, the information about which contours contained the geometric points is not retained.

If you want use the gxSelectToEnd constant for the count parameter, you would typically do the following:

1. Determine the length of the point array by calling this function, passing nil for the data parameter.
2. Allocate enough memory to hold the point array.
3. Call this function again, passing a pointer to the allocated memory in the data parameter.

If you provide an empty or full shape for the source shape, this function posts the error graphic_type_does_not_contain_points.

If you provide a source shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Always returns 1 as the function result
picture	Posts the error graphic_type_does_not_contain_points
text	Always returns 1
glyph	Returns the number of glyphs
layout	Always returns 1

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
index_is_less_than_one	(debugging version)
count_is_less_than_one	(debugging version)
graphic_type_does_not_contain_points	(debugging version)
Warnings
index_out_of_range_in_contour
count_out_of_range

SEE ALSO

For a discussion of geometric points, see the section "Shape Geometry" beginning on page 2-9.

To learn how this function works for typographic shape types, see Inside Macintosh: QuickDraw GX Typography.

To determine the geometry index of a particular geometric point within a shape's geometry, use the GXGetShapeIndex function, which is described on page 2-139.

To replace a range of geometric points in a geometry, use the GXSetShapePoints function, which is described in the next section.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help